aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/acpi
diff options
context:
space:
mode:
authorJonathan Herman <hermanjl@cs.unc.edu>2013-01-17 16:15:55 -0500
committerJonathan Herman <hermanjl@cs.unc.edu>2013-01-17 16:15:55 -0500
commit8dea78da5cee153b8af9c07a2745f6c55057fe12 (patch)
treea8f4d49d63b1ecc92f2fddceba0655b2472c5bd9 /Documentation/acpi
parent406089d01562f1e2bf9f089fd7637009ebaad589 (diff)
Patched in Tegra support.
Diffstat (limited to 'Documentation/acpi')
-rw-r--r--Documentation/acpi/apei/einj.txt63
-rw-r--r--Documentation/acpi/enumeration.txt227
-rw-r--r--Documentation/acpi/initrd_table_override.txt94
3 files changed, 11 insertions, 373 deletions
diff --git a/Documentation/acpi/apei/einj.txt b/Documentation/acpi/apei/einj.txt
index e20b6daaced..5cc699ba545 100644
--- a/Documentation/acpi/apei/einj.txt
+++ b/Documentation/acpi/apei/einj.txt
@@ -47,61 +47,20 @@ directory apei/einj. The following files are provided.
47 47
48- param1 48- param1
49 This file is used to set the first error parameter value. Effect of 49 This file is used to set the first error parameter value. Effect of
50 parameter depends on error_type specified. 50 parameter depends on error_type specified. For memory error, this is
51 physical memory address. Only available if param_extension module
52 parameter is specified.
51 53
52- param2 54- param2
53 This file is used to set the second error parameter value. Effect of 55 This file is used to set the second error parameter value. Effect of
54 parameter depends on error_type specified. 56 parameter depends on error_type specified. For memory error, this is
55 57 physical memory address mask. Only available if param_extension
56- notrigger 58 module parameter is specified.
57 The EINJ mechanism is a two step process. First inject the error, then
58 perform some actions to trigger it. Setting "notrigger" to 1 skips the
59 trigger phase, which *may* allow the user to cause the error in some other
60 context by a simple access to the cpu, memory location, or device that is
61 the target of the error injection. Whether this actually works depends
62 on what operations the BIOS actually includes in the trigger phase.
63
64BIOS versions based in the ACPI 4.0 specification have limited options
65to control where the errors are injected. Your BIOS may support an
66extension (enabled with the param_extension=1 module parameter, or
67boot command line einj.param_extension=1). This allows the address
68and mask for memory injections to be specified by the param1 and
69param2 files in apei/einj.
70
71BIOS versions using the ACPI 5.0 specification have more control over
72the target of the injection. For processor related errors (type 0x1,
730x2 and 0x4) the APICID of the target should be provided using the
74param1 file in apei/einj. For memory errors (type 0x8, 0x10 and 0x20)
75the address is set using param1 with a mask in param2 (0x0 is equivalent
76to all ones). For PCI express errors (type 0x40, 0x80 and 0x100) the
77segment, bus, device and function are specified using param1:
78
79 31 24 23 16 15 11 10 8 7 0
80 +-------------------------------------------------+
81 | segment | bus | device | function | reserved |
82 +-------------------------------------------------+
83
84An ACPI 5.0 BIOS may also allow vendor specific errors to be injected.
85In this case a file named vendor will contain identifying information
86from the BIOS that hopefully will allow an application wishing to use
87the vendor specific extension to tell that they are running on a BIOS
88that supports it. All vendor extensions have the 0x80000000 bit set in
89error_type. A file vendor_flags controls the interpretation of param1
90and param2 (1 = PROCESSOR, 2 = MEMORY, 4 = PCI). See your BIOS vendor
91documentation for details (and expect changes to this API if vendors
92creativity in using this feature expands beyond our expectations).
93
94Example:
95# cd /sys/kernel/debug/apei/einj
96# cat available_error_type # See which errors can be injected
970x00000002 Processor Uncorrectable non-fatal
980x00000008 Memory Correctable
990x00000010 Memory Uncorrectable non-fatal
100# echo 0x12345000 > param1 # Set memory address for injection
101# echo 0xfffffffffffff000 > param2 # Mask - anywhere in this page
102# echo 0x8 > error_type # Choose correctable memory error
103# echo 1 > error_inject # Inject now
104 59
60Injecting parameter support is a BIOS version specific extension, that
61is, it only works on some BIOS version. If you want to use it, please
62make sure your BIOS version has the proper support and specify
63"param_extension=y" in module parameter.
105 64
106For more information about EINJ, please refer to ACPI specification 65For more information about EINJ, please refer to ACPI specification
107version 4.0, section 17.5 and ACPI 5.0, section 18.6. 66version 4.0, section 17.5.
diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt
deleted file mode 100644
index 54469bc81b1..00000000000
--- a/Documentation/acpi/enumeration.txt
+++ /dev/null
@@ -1,227 +0,0 @@
1ACPI based device enumeration
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
4SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
5devices behind serial bus controllers.
6
7In addition we are starting to see peripherals integrated in the
8SoC/Chipset to appear only in ACPI namespace. These are typically devices
9that are accessed through memory-mapped registers.
10
11In order to support this and re-use the existing drivers as much as
12possible we decided to do following:
13
14 o Devices that have no bus connector resource are represented as
15 platform devices.
16
17 o Devices behind real busses where there is a connector resource
18 are represented as struct spi_device or struct i2c_device
19 (standard UARTs are not busses so there is no struct uart_device).
20
21As both ACPI and Device Tree represent a tree of devices (and their
22resources) this implementation follows the Device Tree way as much as
23possible.
24
25The ACPI implementation enumerates devices behind busses (platform, SPI and
26I2C), creates the physical devices and binds them to their ACPI handle in
27the ACPI namespace.
28
29This means that when ACPI_HANDLE(dev) returns non-NULL the device was
30enumerated from ACPI namespace. This handle can be used to extract other
31device-specific configuration. There is an example of this below.
32
33Platform bus support
34~~~~~~~~~~~~~~~~~~~~
35Since we are using platform devices to represent devices that are not
36connected to any physical bus we only need to implement a platform driver
37for the device and add supported ACPI IDs. If this same IP-block is used on
38some other non-ACPI platform, the driver might work out of the box or needs
39some minor changes.
40
41Adding ACPI support for an existing driver should be pretty
42straightforward. Here is the simplest example:
43
44 #ifdef CONFIG_ACPI
45 static struct acpi_device_id mydrv_acpi_match[] = {
46 /* ACPI IDs here */
47 { }
48 };
49 MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match);
50 #endif
51
52 static struct platform_driver my_driver = {
53 ...
54 .driver = {
55 .acpi_match_table = ACPI_PTR(mydrv_acpi_match),
56 },
57 };
58
59If the driver needs to perform more complex initialization like getting and
60configuring GPIOs it can get its ACPI handle and extract this information
61from ACPI tables.
62
63Currently the kernel is not able to automatically determine from which ACPI
64device it should make the corresponding platform device so we need to add
65the ACPI device explicitly to acpi_platform_device_ids list defined in
66drivers/acpi/scan.c. This limitation is only for the platform devices, SPI
67and I2C devices are created automatically as described below.
68
69SPI serial bus support
70~~~~~~~~~~~~~~~~~~~~~~
71Slave devices behind SPI bus have SpiSerialBus resource attached to them.
72This is extracted automatically by the SPI core and the slave devices are
73enumerated once spi_register_master() is called by the bus driver.
74
75Here is what the ACPI namespace for a SPI slave might look like:
76
77 Device (EEP0)
78 {
79 Name (_ADR, 1)
80 Name (_CID, Package() {
81 "ATML0025",
82 "AT25",
83 })
84 ...
85 Method (_CRS, 0, NotSerialized)
86 {
87 SPISerialBus(1, PolarityLow, FourWireMode, 8,
88 ControllerInitiated, 1000000, ClockPolarityLow,
89 ClockPhaseFirst, "\\_SB.PCI0.SPI1",)
90 }
91 ...
92
93The SPI device drivers only need to add ACPI IDs in a similar way than with
94the platform device drivers. Below is an example where we add ACPI support
95to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
96
97 #ifdef CONFIG_ACPI
98 static struct acpi_device_id at25_acpi_match[] = {
99 { "AT25", 0 },
100 { },
101 };
102 MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
103 #endif
104
105 static struct spi_driver at25_driver = {
106 .driver = {
107 ...
108 .acpi_match_table = ACPI_PTR(at25_acpi_match),
109 },
110 };
111
112Note that this driver actually needs more information like page size of the
113eeprom etc. but at the time writing this there is no standard way of
114passing those. One idea is to return this in _DSM method like:
115
116 Device (EEP0)
117 {
118 ...
119 Method (_DSM, 4, NotSerialized)
120 {
121 Store (Package (6)
122 {
123 "byte-len", 1024,
124 "addr-mode", 2,
125 "page-size, 32
126 }, Local0)
127
128 // Check UUIDs etc.
129
130 Return (Local0)
131 }
132
133Then the at25 SPI driver can get this configation by calling _DSM on its
134ACPI handle like:
135
136 struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
137 struct acpi_object_list input;
138 acpi_status status;
139
140 /* Fill in the input buffer */
141
142 status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
143 &input, &output);
144 if (ACPI_FAILURE(status))
145 /* Handle the error */
146
147 /* Extract the data here */
148
149 kfree(output.pointer);
150
151I2C serial bus support
152~~~~~~~~~~~~~~~~~~~~~~
153The slaves behind I2C bus controller only need to add the ACPI IDs like
154with the platform and SPI drivers. However the I2C bus controller driver
155needs to call acpi_i2c_register_devices() after it has added the adapter.
156
157An I2C bus (controller) driver does:
158
159 ...
160 ret = i2c_add_numbered_adapter(adapter);
161 if (ret)
162 /* handle error */
163
164 of_i2c_register_devices(adapter);
165 /* Enumerate the slave devices behind this bus via ACPI */
166 acpi_i2c_register_devices(adapter);
167
168Below is an example of how to add ACPI support to the existing mpu3050
169input driver:
170
171 #ifdef CONFIG_ACPI
172 static struct acpi_device_id mpu3050_acpi_match[] = {
173 { "MPU3050", 0 },
174 { },
175 };
176 MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
177 #endif
178
179 static struct i2c_driver mpu3050_i2c_driver = {
180 .driver = {
181 .name = "mpu3050",
182 .owner = THIS_MODULE,
183 .pm = &mpu3050_pm,
184 .of_match_table = mpu3050_of_match,
185 .acpi_match_table ACPI_PTR(mpu3050_acpi_match),
186 },
187 .probe = mpu3050_probe,
188 .remove = mpu3050_remove,
189 .id_table = mpu3050_ids,
190 };
191
192GPIO support
193~~~~~~~~~~~~
194ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
195and GpioInt. These resources are used be used to pass GPIO numbers used by
196the device to the driver. For example:
197
198 Method (_CRS, 0, NotSerialized)
199 {
200 Name (SBUF, ResourceTemplate()
201 {
202 GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
203 IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
204 0x00, ResourceConsumer,,)
205 {
206 // Pin List
207 0x0055
208 }
209 ...
210
211 Return (SBUF)
212 }
213 }
214
215These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
216specifies the path to the controller. In order to use these GPIOs in Linux
217we need to translate them to the Linux GPIO numbers.
218
219The driver can do this by including <linux/acpi_gpio.h> and then calling
220acpi_get_gpio(path, gpio). This will return the Linux GPIO number or
221negative errno if there was no translation found.
222
223Other GpioIo parameters must be converted first by the driver to be
224suitable to the gpiolib before passing them.
225
226In case of GpioInt resource an additional call to gpio_to_irq() must be
227done before calling request_irq().
diff --git a/Documentation/acpi/initrd_table_override.txt b/Documentation/acpi/initrd_table_override.txt
deleted file mode 100644
index 35c3f541547..00000000000
--- a/Documentation/acpi/initrd_table_override.txt
+++ /dev/null
@@ -1,94 +0,0 @@
1Overriding ACPI tables via initrd
2=================================
3
41) Introduction (What is this about)
52) What is this for
63) How does it work
74) References (Where to retrieve userspace tools)
8
91) What is this about
10---------------------
11
12If the ACPI_INITRD_TABLE_OVERRIDE compile option is true, it is possible to
13override nearly any ACPI table provided by the BIOS with an instrumented,
14modified one.
15
16For a full list of ACPI tables that can be overridden, take a look at
17the char *table_sigs[MAX_ACPI_SIGNATURE]; definition in drivers/acpi/osl.c
18All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
19be overridable, except:
20 - ACPI_SIG_RSDP (has a signature of 6 bytes)
21 - ACPI_SIG_FACS (does not have an ordinary ACPI table header)
22Both could get implemented as well.
23
24
252) What is this for
26-------------------
27
28Please keep in mind that this is a debug option.
29ACPI tables should not get overridden for productive use.
30If BIOS ACPI tables are overridden the kernel will get tainted with the
31TAINT_OVERRIDDEN_ACPI_TABLE flag.
32Complain to your platform/BIOS vendor if you find a bug which is so sever
33that a workaround is not accepted in the Linux kernel.
34
35Still, it can and should be enabled in any kernel, because:
36 - There is no functional change with not instrumented initrds
37 - It provides a powerful feature to easily debug and test ACPI BIOS table
38 compatibility with the Linux kernel.
39
40
413) How does it work
42-------------------
43
44# Extract the machine's ACPI tables:
45cd /tmp
46acpidump >acpidump
47acpixtract -a acpidump
48# Disassemble, modify and recompile them:
49iasl -d *.dat
50# For example add this statement into a _PRT (PCI Routing Table) function
51# of the DSDT:
52Store("HELLO WORLD", debug)
53iasl -sa dsdt.dsl
54# Add the raw ACPI tables to an uncompressed cpio archive.
55# They must be put into a /kernel/firmware/acpi directory inside the
56# cpio archive.
57# The uncompressed cpio archive must be the first.
58# Other, typically compressed cpio archives, must be
59# concatenated on top of the uncompressed one.
60mkdir -p kernel/firmware/acpi
61cp dsdt.aml kernel/firmware/acpi
62# A maximum of: #define ACPI_OVERRIDE_TABLES 10
63# tables are currently allowed (see osl.c):
64iasl -sa facp.dsl
65iasl -sa ssdt1.dsl
66cp facp.aml kernel/firmware/acpi
67cp ssdt1.aml kernel/firmware/acpi
68# Create the uncompressed cpio archive and concatenate the original initrd
69# on top:
70find kernel | cpio -H newc --create > /boot/instrumented_initrd
71cat /boot/initrd >>/boot/instrumented_initrd
72# reboot with increased acpi debug level, e.g. boot params:
73acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
74# and check your syslog:
75[ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
76[ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD"
77
78iasl is able to disassemble and recompile quite a lot different,
79also static ACPI tables.
80
81
824) Where to retrieve userspace tools
83------------------------------------
84
85iasl and acpixtract are part of Intel's ACPICA project:
86http://acpica.org/
87and should be packaged by distributions (for example in the acpica package
88on SUSE).
89
90acpidump can be found in Len Browns pmtools:
91ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
92This tool is also part of the acpica package on SUSE.
93Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
94/sys/firmware/acpi/tables