Documentation/ABI/testing/sysfs-firmware-acpi

   1 What:           /sys/firmware/acpi/fpdt/
   2 Date:           Jan 2021
   3 Contact:        Zhang Rui <rui.zhang@intel.com>
   4 Description:
   5                 ACPI Firmware Performance Data Table (FPDT) provides
   6                 information for firmware performance data for system boot,
   7                 S3 suspend and S3 resume. This sysfs entry contains the
   8                 performance data retrieved from the FPDT.
   9
  10                 boot:
  11                         firmware_start_ns: Timer value logged at the beginning
  12                                 of firmware image execution. In nanoseconds.
  13                         bootloader_load_ns: Timer value logged just prior to
  14                                 loading the OS boot loader into memory.
  15                                 In nanoseconds.
  16                         bootloader_launch_ns: Timer value logged just prior to
  17                                 launching the currently loaded OS boot loader
  18                                 image. In nanoseconds.
  19                         exitbootservice_start_ns: Timer value logged at the
  20                                 point when the OS loader calls the
  21                                 ExitBootServices function for UEFI compatible
  22                                 firmware. In nanoseconds.
  23                         exitbootservice_end_ns: Timer value logged at the point
  24                                 just prior to the OS loader gaining control
  25                                 back from the ExitBootServices function for
  26                                 UEFI compatible firmware. In nanoseconds.
  27                 suspend:
  28                         suspend_start_ns: Timer value recorded at the previous
  29                                 OS write to SLP_TYP upon entry to S3. In
  30                                 nanoseconds.
  31                         suspend_end_ns: Timer value recorded at the previous
  32                                 firmware write to SLP_TYP used to trigger
  33                                 hardware entry to S3. In nanoseconds.
  34                 resume:
  35                         resume_count: A count of the number of S3 resume cycles
  36                                 since the last full boot sequence.
  37                         resume_avg_ns: Average timer value of all resume cycles
  38                                 logged since the last full boot sequence,
  39                                 including the most recent resume. In nanoseconds.
  40                         resume_prev_ns: Timer recorded at the end of the previous
  41                                 platform runtime firmware S3 resume, just prior to
  42                                 handoff to the OS waking vector. In nanoseconds.
  43
  44 What:           /sys/firmware/acpi/bgrt/
  45 Date:           January 2012
  46 Contact:        Matthew Garrett <mjg@redhat.com>
  47 Description:
  48                 The BGRT is an ACPI 5.0 feature that allows the OS
  49                 to obtain a copy of the firmware boot splash and
  50                 some associated metadata. This is intended to be used
  51                 by boot splash applications in order to interact with
  52                 the firmware boot splash in order to avoid jarring
  53                 transitions.
  54
  55                 image: The image bitmap. Currently a 32-bit BMP.
  56                 status: 1 if the image is valid, 0 if firmware invalidated it.
  57                 type: 0 indicates image is in BMP format.
  58
  59                 ======== ===================================================
  60                 version: The version of the BGRT. Currently 1.
  61                 xoffset: The number of pixels between the left of the screen
  62                          and the left edge of the image.
  63                 yoffset: The number of pixels between the top of the screen
  64                          and the top edge of the image.
  65                 ======== ===================================================
  66
  67 What:           /sys/firmware/acpi/hotplug/
  68 Date:           February 2013
  69 Contact:        Rafael J. Wysocki <rafael.j.wysocki@intel.com>
  70 Description:
  71                 There are separate hotplug profiles for different classes of
  72                 devices supported by ACPI, such as containers, memory modules,
  73                 processors, PCI root bridges etc.  A hotplug profile for a given
  74                 class of devices is a collection of settings defining the way
  75                 that class of devices will be handled by the ACPI core hotplug
  76                 code.  Those profiles are represented in sysfs as subdirectories
  77                 of /sys/firmware/acpi/hotplug/.
  78
  79                 The following setting is available to user space for each
  80                 hotplug profile:
  81
  82                 ======== =======================================================
  83                 enabled: If set, the ACPI core will handle notifications of
  84                          hotplug events associated with the given class of
  85                          devices and will allow those devices to be ejected with
  86                          the help of the _EJ0 control method.  Unsetting it
  87                          effectively disables hotplug for the corresponding
  88                          class of devices.
  89                 ======== =======================================================
  90
  91                 The value of the above attribute is an integer number: 1 (set)
  92                 or 0 (unset).  Attempts to write any other values to it will
  93                 cause -EINVAL to be returned.
  94
  95 What:           /sys/firmware/acpi/interrupts/
  96 Date:           February 2008
  97 Contact:        Len Brown <lenb@kernel.org>
  98 Description:
  99                 All ACPI interrupts are handled via a single IRQ,
 100                 the System Control Interrupt (SCI), which appears
 101                 as "acpi" in /proc/interrupts.
 102
 103                 However, one of the main functions of ACPI is to make
 104                 the platform understand random hardware without
 105                 special driver support.  So while the SCI handles a few
 106                 well known (fixed feature) interrupts sources, such
 107                 as the power button, it can also handle a variable
 108                 number of a "General Purpose Events" (GPE).
 109
 110                 A GPE vectors to a specified handler in AML, which
 111                 can do a anything the BIOS writer wants from
 112                 OS context.  GPE 0x12, for example, would vector
 113                 to a level or edge handler called _L12 or _E12.
 114                 The handler may do its business and return.
 115                 Or the handler may send send a Notify event
 116                 to a Linux device driver registered on an ACPI device,
 117                 such as a battery, or a processor.
 118
 119                 To figure out where all the SCI's are coming from,
 120                 /sys/firmware/acpi/interrupts contains a file listing
 121                 every possible source, and the count of how many
 122                 times it has triggered::
 123
 124                   $ cd /sys/firmware/acpi/interrupts
 125                   $ grep . *
 126                   error:             0
 127                   ff_gbl_lock:       0   enable
 128                   ff_pmtimer:        0  invalid
 129                   ff_pwr_btn:        0   enable
 130                   ff_rt_clk:         2  disable
 131                   ff_slp_btn:        0  invalid
 132                   gpe00:             0  invalid
 133                   gpe01:             0   enable
 134                   gpe02:           108   enable
 135                   gpe03:             0  invalid
 136                   gpe04:             0  invalid
 137                   gpe05:             0  invalid
 138                   gpe06:             0   enable
 139                   gpe07:             0   enable
 140                   gpe08:             0  invalid
 141                   gpe09:             0  invalid
 142                   gpe0A:             0  invalid
 143                   gpe0B:             0  invalid
 144                   gpe0C:             0  invalid
 145                   gpe0D:             0  invalid
 146                   gpe0E:             0  invalid
 147                   gpe0F:             0  invalid
 148                   gpe10:             0  invalid
 149                   gpe11:             0  invalid
 150                   gpe12:             0  invalid
 151                   gpe13:             0  invalid
 152                   gpe14:             0  invalid
 153                   gpe15:             0  invalid
 154                   gpe16:             0  invalid
 155                   gpe17:          1084   enable
 156                   gpe18:             0   enable
 157                   gpe19:             0  invalid
 158                   gpe1A:             0  invalid
 159                   gpe1B:             0  invalid
 160                   gpe1C:             0  invalid
 161                   gpe1D:             0  invalid
 162                   gpe1E:             0  invalid
 163                   gpe1F:             0  invalid
 164                   gpe_all:        1192
 165                   sci:            1194
 166                   sci_not:           0
 167
 168                 ===========  ==================================================
 169                 sci          The number of times the ACPI SCI
 170                              has been called and claimed an interrupt.
 171
 172                 sci_not      The number of times the ACPI SCI
 173                              has been called and NOT claimed an interrupt.
 174
 175                 gpe_all      count of SCI caused by GPEs.
 176
 177                 gpeXX        count for individual GPE source
 178
 179                 ff_gbl_lock  Global Lock
 180
 181                 ff_pmtimer   PM Timer
 182
 183                 ff_pwr_btn   Power Button
 184
 185                 ff_rt_clk    Real Time Clock
 186
 187                 ff_slp_btn   Sleep Button
 188
 189                 error        an interrupt that can't be accounted for above.
 190
 191                 invalid      it's either a GPE or a Fixed Event that
 192                              doesn't have an event handler.
 193
 194                 disable      the GPE/Fixed Event is valid but disabled.
 195
 196                 enable       the GPE/Fixed Event is valid and enabled.
 197                 ===========  ==================================================
 198
 199                 Root has permission to clear any of these counters.  Eg.::
 200
 201                   # echo 0 > gpe11
 202
 203                 All counters can be cleared by clearing the total "sci"::
 204
 205                   # echo 0 > sci
 206
 207                 None of these counters has an effect on the function
 208                 of the system, they are simply statistics.
 209
 210                 Besides this, user can also write specific strings to these files
 211                 to enable/disable/clear ACPI interrupts in user space, which can be
 212                 used to debug some ACPI interrupt storm issues.
 213
 214                 Note that only writing to VALID GPE/Fixed Event is allowed,
 215                 i.e. user can only change the status of runtime GPE and
 216                 Fixed Event with event handler installed.
 217
 218                 Let's take power button fixed event for example, please kill acpid
 219                 and other user space applications so that the machine won't shutdown
 220                 when pressing the power button::
 221
 222                   # cat ff_pwr_btn
 223                   0     enabled
 224                   # press the power button for 3 times;
 225                   # cat ff_pwr_btn
 226                   3     enabled
 227                   # echo disable > ff_pwr_btn
 228                   # cat ff_pwr_btn
 229                   3     disabled
 230                   # press the power button for 3 times;
 231                   # cat ff_pwr_btn
 232                   3     disabled
 233                   # echo enable > ff_pwr_btn
 234                   # cat ff_pwr_btn
 235                   4     enabled
 236                   /*
 237                    * this is because the status bit is set even if the enable
 238                    * bit is cleared, and it triggers an ACPI fixed event when
 239                    * the enable bit is set again
 240                    */
 241                   # press the power button for 3 times;
 242                   # cat ff_pwr_btn
 243                   7     enabled
 244                   # echo disable > ff_pwr_btn
 245                   # press the power button for 3 times;
 246                   # echo clear > ff_pwr_btn     /* clear the status bit */
 247                   # echo disable > ff_pwr_btn
 248                   # cat ff_pwr_btn
 249                   7     enabled
 250