Merge branch 'linus' into x86/cleanups
[linux-2.6] / 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
73                 sci - The total number of times the ACPI SCI
74                 has claimed an interrupt.
75
76                 gpe_all - count of SCI caused by GPEs.
77
78                 gpeXX - count for individual GPE source
79
80                 ff_gbl_lock - Global Lock
81
82                 ff_pmtimer - PM Timer
83
84                 ff_pwr_btn - Power Button
85
86                 ff_rt_clk - Real Time Clock
87
88                 ff_slp_btn - Sleep Button
89
90                 error - an interrupt that can't be accounted for above.
91
92                 invalid: it's either a wakeup GPE or a GPE/Fixed Event that
93                         doesn't have an event handler.
94
95                 disable: the GPE/Fixed Event is valid but disabled.
96
97                 enable: the GPE/Fixed Event is valid and enabled.
98
99                 Root has permission to clear any of these counters.  Eg.
100                 # echo 0 > gpe11
101
102                 All counters can be cleared by clearing the total "sci":
103                 # echo 0 > sci
104
105                 None of these counters has an effect on the function
106                 of the system, they are simply statistics.
107
108                 Besides this, user can also write specific strings to these files
109                 to enable/disable/clear ACPI interrupts in user space, which can be
110                 used to debug some ACPI interrupt storm issues.
111
112                 Note that only writting to VALID GPE/Fixed Event is allowed,
113                 i.e. user can only change the status of runtime GPE and
114                 Fixed Event with event handler installed.
115
116                 Let's take power button fixed event for example, please kill acpid
117                 and other user space applications so that the machine won't shutdown
118                 when pressing the power button.
119                 # cat ff_pwr_btn
120                 0
121                 # press the power button for 3 times;
122                 # cat ff_pwr_btn
123                 3
124                 # echo disable > ff_pwr_btn
125                 # cat ff_pwr_btn
126                 disable
127                 # press the power button for 3 times;
128                 # cat ff_pwr_btn
129                 disable
130                 # echo enable > ff_pwr_btn
131                 # cat ff_pwr_btn
132                 4
133                 /*
134                  * this is because the status bit is set even if the enable bit is cleared,
135                  * and it triggers an ACPI fixed event when the enable bit is set again
136                  */
137                 # press the power button for 3 times;
138                 # cat ff_pwr_btn
139                 7
140                 # echo disable > ff_pwr_btn
141                 # press the power button for 3 times;
142                 # echo clear > ff_pwr_btn       /* clear the status bit */
143                 # echo disable > ff_pwr_btn
144                 # cat ff_pwr_btn
145                 7
146