Documentation/ABI/testing/sysfs-firmware-acpi

   1 What:           /sys/firmware/acpi/interrupts/
   2 Date:           February 2008
   3 Contact:        Len Brown <lenb@kernel.org>
   4 Description:
   5                 All ACPI interrupts are handled via a single IRQ,
   6                 the System Control Interrupt (SCI), which appears
   7                 as "acpi" in /proc/interrupts.
   8
   9                 However, one of the main functions of ACPI is to make
  10                 the platform understand random hardware without
  11                 special driver support.  So while the SCI handles a few
  12                 well known (fixed feature) interrupts sources, such
  13                 as the power button, it can also handle a variable
  14                 number of a "General Purpose Events" (GPE).
  15
  16                 A GPE vectors to a specified handler in AML, which
  17                 can do a anything the BIOS writer wants from
  18                 OS context.  GPE 0x12, for example, would vector
  19                 to a level or edge handler called _L12 or _E12.
  20                 The handler may do its business and return.
  21                 Or the handler may send send a Notify event
  22                 to a Linux device driver registered on an ACPI device,
  23                 such as a battery, or a processor.
  24
  25                 To figure out where all the SCI's are coming from,
  26                 /sys/firmware/acpi/interrupts contains a file listing
  27                 every possible source, and the count of how many
  28                 times it has triggered.
  29
  30                 $ cd /sys/firmware/acpi/interrupts
  31                 $ grep . *
  32                 error:       0
  33                 ff_gbl_lock:       0   enable
  34                 ff_pmtimer:       0  invalid
  35                 ff_pwr_btn:       0   enable
  36                 ff_rt_clk:       2  disable
  37                 ff_slp_btn:       0  invalid
  38                 gpe00:       0  invalid
  39                 gpe01:       0   enable
  40                 gpe02:     108   enable
  41                 gpe03:       0  invalid
  42                 gpe04:       0  invalid
  43                 gpe05:       0  invalid
  44                 gpe06:       0   enable
  45                 gpe07:       0   enable
  46                 gpe08:       0  invalid
  47                 gpe09:       0  invalid
  48                 gpe0A:       0  invalid
  49                 gpe0B:       0  invalid
  50                 gpe0C:       0  invalid
  51                 gpe0D:       0  invalid
  52                 gpe0E:       0  invalid
  53                 gpe0F:       0  invalid
  54                 gpe10:       0  invalid
  55                 gpe11:       0  invalid
  56                 gpe12:       0  invalid
  57                 gpe13:       0  invalid
  58                 gpe14:       0  invalid
  59                 gpe15:       0  invalid
  60                 gpe16:       0  invalid
  61                 gpe17:    1084   enable
  62                 gpe18:       0   enable
  63                 gpe19:       0  invalid
  64                 gpe1A:       0  invalid
  65                 gpe1B:       0  invalid
  66                 gpe1C:       0  invalid
  67                 gpe1D:       0  invalid
  68                 gpe1E:       0  invalid
  69                 gpe1F:       0  invalid
  70                 gpe_all:    1192
  71                 sci:    1194
  72                 sci_not:     0
  73
  74                 sci - The number of times the ACPI SCI
  75                 has been called and claimed an interrupt.
  76
  77                 sci_not - The number of times the ACPI SCI
  78                 has been called and NOT claimed an interrupt.
  79
  80                 gpe_all - count of SCI caused by GPEs.
  81
  82                 gpeXX - count for individual GPE source
  83
  84                 ff_gbl_lock - Global Lock
  85
  86                 ff_pmtimer - PM Timer
  87
  88                 ff_pwr_btn - Power Button
  89
  90                 ff_rt_clk - Real Time Clock
  91
  92                 ff_slp_btn - Sleep Button
  93
  94                 error - an interrupt that can't be accounted for above.
  95
  96                 invalid: it's either a GPE or a Fixed Event that
  97                         doesn't have an event handler.
  98
  99                 disable: the GPE/Fixed Event is valid but disabled.
 100
 101                 enable: the GPE/Fixed Event is valid and enabled.
 102
 103                 Root has permission to clear any of these counters.  Eg.
 104                 # echo 0 > gpe11
 105
 106                 All counters can be cleared by clearing the total "sci":
 107                 # echo 0 > sci
 108
 109                 None of these counters has an effect on the function
 110                 of the system, they are simply statistics.
 111
 112                 Besides this, user can also write specific strings to these files
 113                 to enable/disable/clear ACPI interrupts in user space, which can be
 114                 used to debug some ACPI interrupt storm issues.
 115
 116                 Note that only writting to VALID GPE/Fixed Event is allowed,
 117                 i.e. user can only change the status of runtime GPE and
 118                 Fixed Event with event handler installed.
 119
 120                 Let's take power button fixed event for example, please kill acpid
 121                 and other user space applications so that the machine won't shutdown
 122                 when pressing the power button.
 123                 # cat ff_pwr_btn
 124                 0       enabled
 125                 # press the power button for 3 times;
 126                 # cat ff_pwr_btn
 127                 3       enabled
 128                 # echo disable > ff_pwr_btn
 129                 # cat ff_pwr_btn
 130                 3       disabled
 131                 # press the power button for 3 times;
 132                 # cat ff_pwr_btn
 133                 3       disabled
 134                 # echo enable > ff_pwr_btn
 135                 # cat ff_pwr_btn
 136                 4       enabled
 137                 /*
 138                  * this is because the status bit is set even if the enable bit is cleared,
 139                  * and it triggers an ACPI fixed event when the enable bit is set again
 140                  */
 141                 # press the power button for 3 times;
 142                 # cat ff_pwr_btn
 143                 7       enabled
 144                 # echo disable > ff_pwr_btn
 145                 # press the power button for 3 times;
 146                 # echo clear > ff_pwr_btn       /* clear the status bit */
 147                 # echo disable > ff_pwr_btn
 148                 # cat ff_pwr_btn
 149                 7       enabled
 150