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