Documentation/acpi/method-tracing.txt

   1 ACPICA Trace Facility
   2
   3 Copyright (C) 2015, Intel Corporation
   4 Author: Lv Zheng <lv.zheng@intel.com>
   5
   6
   7 Abstract:
   8
   9 This document describes the functions and the interfaces of the method
  10 tracing facility.
  11
  12 1. Functionalities and usage examples:
  13
  14    ACPICA provides method tracing capability. And two functions are
  15    currently implemented using this capability.
  16
  17    A. Log reducer
  18    ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is
  19    enabled. The debugging messages which are deployed via
  20    ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component
  21    level (known as debug layer, configured via
  22    /sys/module/acpi/parameters/debug_layer) and per-type level (known as
  23    debug level, configured via /sys/module/acpi/parameters/debug_level).
  24
  25    But when the particular layer/level is applied to the control method
  26    evaluations, the quantity of the debugging outputs may still be too
  27    large to be put into the kernel log buffer. The idea thus is worked out
  28    to only enable the particular debug layer/level (normally more detailed)
  29    logs when the control method evaluation is started, and disable the
  30    detailed logging when the control method evaluation is stopped.
  31
  32    The following command examples illustrate the usage of the "log reducer"
  33    functionality:
  34    a. Filter out the debug layer/level matched logs when control methods
  35       are being evaluated:
  36       # cd /sys/module/acpi/parameters
  37       # echo "0xXXXXXXXX" > trace_debug_layer
  38       # echo "0xYYYYYYYY" > trace_debug_level
  39       # echo "enable" > trace_state
  40    b. Filter out the debug layer/level matched logs when the specified
  41       control method is being evaluated:
  42       # cd /sys/module/acpi/parameters
  43       # echo "0xXXXXXXXX" > trace_debug_layer
  44       # echo "0xYYYYYYYY" > trace_debug_level
  45       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
  46       # echo "method" > /sys/module/acpi/parameters/trace_state
  47    c. Filter out the debug layer/level matched logs when the specified
  48       control method is being evaluated for the first time:
  49       # cd /sys/module/acpi/parameters
  50       # echo "0xXXXXXXXX" > trace_debug_layer
  51       # echo "0xYYYYYYYY" > trace_debug_level
  52       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
  53       # echo "method-once" > /sys/module/acpi/parameters/trace_state
  54    Where:
  55       0xXXXXXXXX/0xYYYYYYYY: Refer to Documentation/acpi/debug.txt for
  56                              possible debug layer/level masking values.
  57       \PPPP.AAAA.TTTT.HHHH: Full path of a control method that can be found
  58                             in the ACPI namespace. It needn't be an entry
  59                             of a control method evaluation.
  60
  61    B. AML tracer
  62
  63    There are special log entries added by the method tracing facility at
  64    the "trace points" the AML interpreter starts/stops to execute a control
  65    method, or an AML opcode. Note that the format of the log entries are
  66    subject to change:
  67      [    0.186427]   exdebug-0398 ex_trace_point        : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
  68      [    0.186630]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905c88:If] execution.
  69      [    0.186820]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905cc0:LEqual] execution.
  70      [    0.187010]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905a20:-NamePath-] execution.
  71      [    0.187214]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905a20:-NamePath-] execution.
  72      [    0.187407]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905f60:One] execution.
  73      [    0.187594]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905f60:One] execution.
  74      [    0.187789]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905cc0:LEqual] execution.
  75      [    0.187980]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905cc0:Return] execution.
  76      [    0.188146]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905f60:One] execution.
  77      [    0.188334]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905f60:One] execution.
  78      [    0.188524]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905cc0:Return] execution.
  79      [    0.188712]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905c88:If] execution.
  80      [    0.188903]   exdebug-0398 ex_trace_point        : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
  81
  82    Developers can utilize these special log entries to track the AML
  83    interpretion, thus can aid issue debugging and performance tuning. Note
  84    that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()
  85    macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling
  86    "AML tracer" logs.
  87
  88    The following command examples illustrate the usage of the "AML tracer"
  89    functionality:
  90    a. Filter out the method start/stop "AML tracer" logs when control
  91       methods are being evaluated:
  92       # cd /sys/module/acpi/parameters
  93       # echo "0x80" > trace_debug_layer
  94       # echo "0x10" > trace_debug_level
  95       # echo "enable" > trace_state
  96    b. Filter out the method start/stop "AML tracer" when the specified
  97       control method is being evaluated:
  98       # cd /sys/module/acpi/parameters
  99       # echo "0x80" > trace_debug_layer
 100       # echo "0x10" > trace_debug_level
 101       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
 102       # echo "method" > trace_state
 103    c. Filter out the method start/stop "AML tracer" logs when the specified
 104       control method is being evaluated for the first time:
 105       # cd /sys/module/acpi/parameters
 106       # echo "0x80" > trace_debug_layer
 107       # echo "0x10" > trace_debug_level
 108       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
 109       # echo "method-once" > trace_state
 110    d. Filter out the method/opcode start/stop "AML tracer" when the
 111       specified control method is being evaluated:
 112       # cd /sys/module/acpi/parameters
 113       # echo "0x80" > trace_debug_layer
 114       # echo "0x10" > trace_debug_level
 115       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
 116       # echo "opcode" > trace_state
 117    e. Filter out the method/opcode start/stop "AML tracer" when the
 118       specified control method is being evaluated for the first time:
 119       # cd /sys/module/acpi/parameters
 120       # echo "0x80" > trace_debug_layer
 121       # echo "0x10" > trace_debug_level
 122       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
 123       # echo "opcode-opcode" > trace_state
 124
 125   Note that all above method tracing facility related module parameters can
 126   be used as the boot parameters, for example:
 127       acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
 128       acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once
 129
 130 2. Interface descriptions:
 131
 132    All method tracing functions can be configured via ACPI module
 133    parameters that are accessible at /sys/module/acpi/parameters/:
 134
 135    trace_method_name
 136         The full path of the AML method that the user wants to trace.
 137         Note that the full path shouldn't contain the trailing "_"s in its
 138         name segments but may contain "\" to form an absolute path.
 139
 140    trace_debug_layer
 141         The temporary debug_layer used when the tracing feature is enabled.
 142         Using ACPI_EXECUTER (0x80) by default, which is the debug_layer
 143         used to match all "AML tracer" logs.
 144
 145    trace_debug_level
 146         The temporary debug_level used when the tracing feature is enabled.
 147         Using ACPI_LV_TRACE_POINT (0x10) by default, which is the
 148         debug_level used to match all "AML tracer" logs.
 149
 150    trace_state
 151         The status of the tracing feature.
 152         Users can enable/disable this debug tracing feature by executing
 153         the following command:
 154             # echo string > /sys/module/acpi/parameters/trace_state
 155         Where "string" should be one of the followings:
 156         "disable"
 157             Disable the method tracing feature.
 158         "enable"
 159             Enable the method tracing feature.
 160             ACPICA debugging messages matching
 161             "trace_debug_layer/trace_debug_level" during any method
 162             execution will be logged.
 163         "method"
 164             Enable the method tracing feature.
 165             ACPICA debugging messages matching
 166             "trace_debug_layer/trace_debug_level" during method execution
 167             of "trace_method_name" will be logged.
 168         "method-once"
 169             Enable the method tracing feature.
 170             ACPICA debugging messages matching
 171             "trace_debug_layer/trace_debug_level" during method execution
 172             of "trace_method_name" will be logged only once.
 173         "opcode"
 174             Enable the method tracing feature.
 175             ACPICA debugging messages matching
 176             "trace_debug_layer/trace_debug_level" during method/opcode
 177             execution of "trace_method_name" will be logged.
 178         "opcode-once"
 179             Enable the method tracing feature.
 180             ACPICA debugging messages matching
 181             "trace_debug_layer/trace_debug_level" during method/opcode
 182             execution of "trace_method_name" will be logged only once.
 183         Note that, the difference between the "enable" and other feature
 184         enabling options are:
 185         1. When "enable" is specified, since
 186            "trace_debug_layer/trace_debug_level" shall apply to all control
 187            method evaluations, after configuring "trace_state" to "enable",
 188            "trace_method_name" will be reset to NULL.
 189         2. When "method/opcode" is specified, if
 190            "trace_method_name" is NULL when "trace_state" is configured to
 191            these options, the "trace_debug_layer/trace_debug_level" will
 192            apply to all control method evaluations.