Documentation: ACPI: move method-tracing.txt to firmware-guide/acpi and convert to rsST

-192

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 following: 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.

+1

Documentation/firmware-guide/acpi/index.rst

··· 13 13 enumeration 14 14 osi 15 15 method-customizing 16 + method-tracing 16 17 DSD-properties-rules 17 18 debug 18 19 gpio-properties

+238

Documentation/firmware-guide/acpi/method-tracing.rst

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