Documentation/ABI/testing/sysfs-firmware-acpi

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